Financial Functions
| Name | Description | Example |
|---|---|---|
| discountFactors(<rate>) | Returns an array of discount factors for the discount rate <rate>. The discount rate refers to the period rate and all periods are assumed to have the same length (i.e., "Mixed" periodicity is not supported - see General Tab). The elements of the array are the reciprocals of the powers of (1 + <rate>). Note that the first entry in the array is 1, the second 1 / (1 + <rate>), and so on, with the denominator (1 + <rate>) elevated to powers 2, 3, ... Discount factors are related to the way in which the npv(<rate>, <cashflow>) function is calculated. The difference is that in the npv function the first element of cashflow is divided by (1 + <rate>), which is not the first discount factor but the second. More precisely, the relationship between the two functions is: discountFactors(<rate>) / (1 + <rate>) * cashflow = npv(<rate>, <cashflow>) | discountFactors(0.1) |
| irr(<array>) | Returns the Internal Rate of Return of <array>, calculated at regular intervals using the reporting periods defined in the General Tab. When the periodicity is "Mixed" the rate is annual (see General Tab). | irr("Cash Flow: Cash Flow After Tax") |
| npv(<rate>, <array>) | Returns the Net Present Value of <array> with the discount rate <rate>. The discount rate must be a (single) Number. When the periodicity is "Mixed" the rate is annual (see General Tab). Otherwise it refers to the rate for the given period. Compare discountFactors above. | npv(0.1, "Cash Flow: Cash Flow After Tax") |
| payment(<rate>, <periods>, <pv>, <fv>, <type>) | Returns the period payment on a loan amount of present value <pv>, interest rate of <rate> paid over <periods> periods with a balance of future value <fv> after the final payment. If <type> = 1, payment occurs at the start of each period. If <type> = 0, payment occurs at the end of each period. The <rate> argument refers to the period rate and all periods are assumed to have the same length. | payment(0.1, 10, "Loan: Loan Amount", 0, 1) |
| paymentCF(<rate>, <periods>, <pv>, <fv>, <type>, <firstPeriod>) | Returns the cash flow for receipt and repayment on a loan amount of present value <pv>, interest rate of <rate> paid over <periods> periods with a balance of future value <fv> after the final payment. If <type> = 1, payment occurs at the start of period. If <type> = 0, payment occurs at the end of period. The cash flow array starts in period <firstPeriod> with the positive cash flow value of <pv> and continues in the following <periods> periods with the negative loan installments. The <rate> argument refers to the period rate and all periods are assumed to have the same length. | paymentCF(0.1, 10, "Loan: Loan Amount", 0, 1,10) |
| periodXIRR(<array>, <dates>) | Returns an array of the running period Internal Rate of Return of <array>. Cash flows in <array> occur on <dates>, that is an array of dates. The Internal Rate is calculated using all values in <array> up to and including the current value. The Internal Rate of Return is based on whatever period length is selected. This function can be used if periods in the project are of varying length, i.e. if the "Mixed" period option is selected (see General Tab). | periodXIRR("Cash Flow: Cash Flow After Tax", "Periodicity Start Dates") |
| periodXIRRLimit(<array>, <dates>, <startDate>, <endDate>) | Returns an array of the running period Internal Rate of Return of <array> within a given span. Cash flows in <array> occur on <dates>, that is an array of dates. The Internal Rate is calculated using all values in <array> up to and including the current value. The Internal Rate of Return is based on whatever period length is selected. Only the cash flows between <startDate> and <endDate> are included. This function can be used if periods in the project are of varying length, i.e. if the "Mixed" period option is selected (see General Tab). | periodXIRRLimit("Cash Flow", "Periodicity End Dates", "Development Phase Start Date", "Development Phase End Date") |
| periodXNPV(<rate>, <array>, <dates>) | Returns an array of the Net Present Value of <array> calculated using the discount rate <rate>. Cash flows in <array> occur on <dates>, that is an array of dates. This function can be used if periods in the project are of varying length, i.e. if the "Mixed" period option is selected (see General Tab). The discount rate can be a single or array value. It is assumed to be annual. | periodXNPV(0.1, "Cash Flow: Cash Flow After Tax", "Periodicity Start Dates") or periodXNPV("Escalation: Discount Rates", "Cash Flow: Cash Flow After Tax", "Periodicity Start Dates") |
| periodXNPVLimit(<rate>, <array>, <dates>, <startDate>, <endDate>) | Returns an array of the Net Present Value of <array> calculated using the discount rate <rate> and cash flows in <array> occur on <dates>, that is an array of dates. Only the cash flows between <startDate> and <endDate> are included. This function can be used if periods in the project are of varying length, i.e. if the "Mixed" period option is selected (see General Tab). The discount rate can be a single or array value. It is assumed to be annual. | periodXNPVLimit(0.1, "Cash Flow", "Periodicity End Dates", "Project Start Date", "Project End Date") |
| xIRR(<array>, <dates>) | Returns the Internal Rate of Return of <array>. Cash flows in <array> occur on <dates>, that is an array of dates which need not be regularly distributed. The xIRR function takes into account leap years. | xIRRLimit("Cash Flow: Cash Flow After Tax", "Project Start Date", "Project End Date") |
| xIRRLimit(<array>, <dates>, <startDate>, <endDate>) | Returns the Internal Rate of Return of <array> within a given span. Cash flows in <array> occur on <dates>. Only the cash flows between <startDate> and <endDate> are included. | xIRR("Cash Flow: Cash Flow After Tax", "Periodicity Start Dates") |
| xNPV(<rate>, <array>, <dates>) | Returns the cumulative Net Present Value of <array> with the discount rate <rate>. Cash flows in <array> occur on <dates>, that is an array of dates. The discount rate is assumed to be annual. | xNPV(0.1, "Cash Flow: Cash Flow After Tax", "Project Start Dates") |
| xNPVLimit(<rate>, <array>, <dates>, <startDate>, <endDate>) | Returns the cumulative Net Present Value of <array> with the discount rate <rate> and cash flows in <array> occur on <dates>, that is an array of dates. Only the cash flows between <startDate> and <endDate> are included. The discount rate is assumed to be annual. | xNPVLimit(0.1, "Cash Flow", "Periodicity End Dates", "Lease Start Date", "Lease End Date") |
| yearlyIRR(<array>) | Returns an array of the running Internal Rate of Return of <array>. The Internal Rate is calculated using all values in <array> up to and including the current value. The Internal Rate of Return is based on whatever period length is selected. This function should only be used if all periods in the project are of equal length. It should not be used with "Mixed" period (see General Tab). | yearlyIRR("Cash Flow: Cash Flow After Tax") |
| yearlyNPV(<rate>, <array>) | Returns an array of the Net Present Values of <array> calculated using the discount rate <rate>. Note that the <rate> argument is interpreted as an annual rate, rather than a rate associated with the individual period. Thus, for monthly periods, the annual rate provided as an argument is internally divided by 12 and contributes evenly to the cash flow associated to that month. The parameter rate can be a single or array value. | yearlyNPV(0.1, "Cash Flow: Cash Flow After Tax") or yearlyNPV("Escalation: Discount Rates", "Cash Flow: Cash Flow After Tax") |
Financial functions that return a single value are excluded from the Functions list in PetroVR Plan, but are available in PetroVR Econ: they are irr, npv, payment, xIRR, xIRRLimit, xNPV, xNPVLimit. This is so because in Plan it is preferable to simply use the current values (i.e., values at the current step of the simulation) of runtime variables instead of reading them from a list or array.
Internal Rate of Return functions (irr, xIRR, etc.) will return an Undefined result if the NPV is always negative (or positive) regardless of the interest rate. This is typically observed when there is no production (reservoir failure, etc.)
The yearlyIRR function is inherently slow because it has to apply an iterative method for every entry of the array. This iterative method is the one that computes the value of IRR for the running cashflow that ends in the corresponding period. Because of this, it is preferable that you define a variable for every invocation of the yearlyIRR function and use this variable in other expressions instead of repeatedly embedding the function in these expressions. This factorization of the model will let PetroVR Econ compute the function only once. This practice, which can also be also recommended for any other function, is critical for yearlyIRR, especially when the number of periods is large - e.g., when using monthly periodicity; see General Tab.